:- module(gap).
:- export gap_query_string / 3.
:- export gap_query / 3.
:- export gap_command / 2.
:- export gap_restart / 0.
:- export gap_shutdown / 0.
:- export gap_ensure_started / 0.
:- export gap_running / 0.
:- comment(summary, "Library for interfacing with the GAP computational algebra system").
:- comment(desc, html("   This library provides an interface to the GAP computational algebra\n   system (see <A HREF=\"http://www.gap-system.org/\">www.gap-system.org</A>).  GAP must be installed and appear in the\n   user's path in order for this library to work.<P>\n\n   Commands can be sent to GAP using the gap_command/2 predicate.  If there\n   are results that need to be returned to ECLiPSe, use gap_query/3 or\n   gap_query_string/3.  Normally GAP will be started automatically when it\n   is needed, and shut down automatically when the ECLiPSe session ends, but\n   some manual control is available through gap_ensure_started/0,\n   gap_shutdown/0 and gap_restart/0.  gap_running/0 can be used to determine\n   whether a GAP session is currently active.<P>\n\n   The current implementation of the library only supports one GAP session\n   at a time, to be shared amongst all software components that use the\n   library.  In future we expect to allow multiple concurrent independent\n   sessions through the use of handles.<P>\n\n   This library supports the following options (see library(config_opts)):\n   <DL>\n   <DT>gap_reporting_level</DT>\n       <DD>Controls how much reporting output the GAP interface generates.\n       Valid levels are:<P>\n       <DL>\n       <DT>silent</DT>\n           <DD>Generate no reporting output under any circumstances.</DD>\n       <DT>error</DT>\n           <DD>Generate reporting output only when an error occurs.</DD>\n       <DT>standard</DT>\n           <DD>Generate basic reporting output.</DD>\n       <DT>verbose</DT>\n           <DD>Generate lots of reporting output, including all commands and\n           queries sent to/from GAP.</DD>\n       </DL><P>\n       The default is standard.  Verbose can be useful for debugging.<P></DD>\n\n   <DT>gap_reporting_stream</DT>\n       <DD>Specifies the stream to send reporting output to.  By default,\n       ECLiPSe's standard output stream is used.</DD>\n   </DL>\n\n   This library is still experimental and is expected to evolve.  Feedback,\n   suggestions, problem reports, etc. welcome.<P>\n\n   Please note that this library currently does not work on Windows machines\n   since it relies on named pipes, which are currently unsupported by\n   cygwin.<P>\n")).
:- comment(see_also, [library(config_opts)]).
:- comment(index, ["gap_reporting_level", "gap_reporting_stream"]).
:- comment(author, "Warwick Harvey, Steve Linton, Ian Gent and others").
:- comment(status, "evolving").
:- comment(gap_command / 2, [summary : "Send a command to GAP", args : ["Format" : "Format string", "Args" : "List of arguments"], amode : gap_command(++, +), see_also : [gap_query / 3, gap_query_string / 3, printf / 2], desc : html("   Sends a command to GAP.  The command is specified using Format and Args a\n   la printf/2.  It is not necessary to terminate the GAP command with a\n   semicolon.<P>\n\n   If there is no currently active GAP session, one is started before\n   sending the command.\n")]).
:- comment(gap_ensure_started / 0, [summary : "Make sure there is a GAP session active", see_also : [gap_shutdown / 0, gap_restart / 0, gap_running / 0], desc : html("   Makes sure that there is a GAP session currently active, by starting GAP\n   if required.  It is normally not necessary to call this predicate\n   directly, since sending any GAP command or query will automatically start\n   GAP if GAP is not currently running.  However, there may be circumstances\n   where one wishes to force GAP to start, to avoid the start-up delay later\n   when the first command is sent.\n")]).
:- comment(gap_query / 3, [summary : "Query GAP", args : ["Format" : "Format string", "Args" : "List of arguments", "Result" : "Result (term)"], amode : gap_query(++, +, ?), see_also : [gap_query_string / 3, gap_command / 2, printf / 2], desc : html("   Evaluates an expression in GAP and returns the result as an ECLiPSe term.\n   The expression is specified using Format and Args a la printf/2, and\n   should be a valid GAP expression (no terminating semicolon).  The result\n   is returned as an ECLiPSe term in Result (it is an error if the result\n   returned from GAP is not a valid ECLiPSe term).<P>\n\n   If there is no currently active GAP session, one is started before\n   sending the query.\n")]).
:- comment(gap_query_string / 3, [summary : "Query GAP", args : ["Format" : "Format string", "Args" : "List of arguments", "Result" : "Result (string)"], amode : gap_query_string(++, +, ?), see_also : [gap_query / 3, gap_command / 2, printf / 2], desc : html("   Evaluates an expression in GAP and returns the result as a string.  The\n   expression is specified using Format and Args a la printf/2, and should\n   be a valid GAP expression (no terminating semicolon).  The result is\n   returned as a string in Result.<P>\n\n   If there is no currently active GAP session, one is started before\n   sending the query.\n")]).
:- comment(gap_restart / 0, [summary : "Restart a GAP session", see_also : [gap_ensure_started / 0, gap_shutdown / 0, gap_running / 0], desc : html("   Restarts the currently active GAP session.  This is useful if one wishes\n   to discard GAP's current state and start again with a fresh session (all\n   GAP state is lost).<P>\n\n   This predicate is simply a short-hand for calling gap_shutdown/0 and then\n   gap_ensure_started/0.\n")]).
:- comment(gap_running / 0, [summary : "Query whether a GAP session is currently active", see_also : [gap_ensure_started / 0, gap_shutdown / 0, gap_restart / 0], desc : html("   This predicate succeeds if there is a GAP session currently active and\n   fails if there is not.\n")]).
:- comment(gap_shutdown / 0, [summary : "Shut down a GAP session", see_also : [gap_ensure_started / 0, gap_restart / 0, gap_running / 0], desc : html("   Shuts down the currently active GAP session if there is one.  With recent\n   versions of ECLiPSe it is not normally necessary to call this explicitly;\n   GAP will be shut down automatically before the ECLiPSe session ends.\n   However, there may be circumstances where one wishes to force GAP to shut\n   down before the session ends, and on older versions of ECLiPSe a manual\n   shutdown is required in order to terminate the GAP process and clean up\n   the named pipes used for communication.\n")]).